Available Native APIs

Catalyst Core provides a comprehensive set of native APIs through React hooks that enable seamless integration between web and native platforms in universal apps.

Available Native APIs

Catalyst Core provides native APIs through React hooks with a common interface for consistent development experience across web and native platforms.

Native Hooks Overview

📷 Camera APIs

Hook/Function	Description
useCamera()	Photo capture with integrated permission management, supports takePhoto, requestPermission operations
useCameraPermission()	Standalone camera permission management
requestCameraPermission()	Promise-based permission request

📁 File Management APIs

Hook/Function	Description
useFilePicker()	File selection with MIME type filtering and transport tracking
useIntent()	Open files with external applications, includes download progress

📳 Haptic Feedback APIs

Hook/Function	Description
useHapticFeedback()	Platform-specific haptic feedback with capability detection and web fallbacks
requestHapticFeedback()	Promise-based haptic requests

💾 Universal Storage API

Hook/Function	Description
Storage	Universal storage interface (localStorage + native persistence)

WebBridge Initialization

Initialize WebBridge in client/index.js before using any native hooks

client/index.js - Required Setup

1// client/index.js - Initialize WebBridge at app startup
2import React from "react"
3import "./styles"
4import { hydrateRoot } from "react-dom/client"
5import { loadableReady } from "@loadable/component"
6import { Provider } from "react-redux"
7import { RouterProvider } from "@tata1mg/router"
8import clientRouter from "catalyst-core/router/ClientRouter"
9import configureStore from "@store"
10import WebBridge from "catalyst-core/WebBridge"
11
12window.addEventListener("load", () => {
13    loadableReady(() => {
14        const { __ROUTER_INITIAL_DATA__: routerInitialData, __INITIAL_STATE__ } = window
15        const store = configureStore(__INITIAL_STATE__ || {})
16
17        const router = clientRouter({ store, routerInitialState: routerInitialData })
18
19        const Application = (
20            <Provider store={store} serverState={__INITIAL_STATE__}>
21                <React.StrictMode>
22                    <RouterProvider router={router} />
23                </React.StrictMode>
24            </Provider>
25        )
26        
27        // Initialize WebBridge for native communication
28        WebBridge.init(); // ⭐ Required for native hooks
29        
30        const container = document.getElementById("app")
31        hydrateRoot(container, Application)
32    })
33})

Common Interface Example

All hooks follow the same standardized interface pattern. Here's the camera hook demonstrating the common interface:

CameraComponent.js

1// Using Camera Hook with Common Interface
2import React from 'react';
3import { useCamera } from "catalyst-core/hooks";
4
5function CameraComponent() {
6  const { 
7    // Standard Interface Properties
8    data: photo,        // Hook-specific result data
9    loading,            // Operation in progress
10    error,              // Standardized error object
11    progress,           // Detailed progress information
12    isWeb,              // Environment detection
13    isNative,           // Environment detection
14    
15    // Standard Actions
16    execute,            // Primary function (takePhoto)
17    clear,              // Clear data and reset state
18    clearError,         // Clear error state only
19    
20    // Camera-specific properties (legacy compatibility)
21    permission,         // Camera permission status
22    takePhoto,          // Semantic alias for execute
23    clearPhoto          // Legacy alias for clear
24  } = useCamera();
25
26  const handleTakePhoto = () => {
27    if (isNative) {
28      execute('takePhoto'); // or just execute() for default
29    } else {
30      console.warn('Camera requires native environment');
31    }
32  };
33
34  return (
35    <div>
36      <button onClick={handleTakePhoto} disabled={loading}>
37        {loading ? 'Taking Photo...' : 'Take Photo'}
38      </button>
39      
40      {/* Progress Tracking */}
41      {loading && progress && (
42        <div>
43          <p>Status: {progress.state}</p>
44          {progress.message && <p>{progress.message}</p>}
45          {progress.transport && <small>Transport: {progress.transport}</small>}
46        </div>
47      )}
48      
49      {/* Standardized Error Display */}
50      {error && (
51        <div className="error">
52          <h4>{error.message}</h4>
53          <p>{error.details}</p>
54          {error.recoverable && (
55            <>
56              <p><strong>Action:</strong> {error.action}</p>
57              <button onClick={clearError}>Try Again</button>
58            </>
59          )}
60          <small>Code: {error.code} | Category: {error.category}</small>
61        </div>
62      )}
63      
64      {/* Photo Display */}
65      {photo && (
66        <div>
67          <img src={photo.fileSrc} alt="Captured" />
68          <p>Transport: {photo.transport}</p>
69          <p>Size: {photo.size} bytes</p>
70          <button onClick={clear}>Clear Photo</button>
71        </div>
72      )}
73      
74      <p>Environment: {isNative ? 'Native' : 'Web'}</p>
75      <p>Permission: {permission?.status || 'Unknown'}</p>
76    </div>
77  );
78}

Implementation Notes

Initialization: Always call WebBridge.init() before using hooks
Common Interface: All hooks use execute() as primary function with semantic aliases
Error Handling: Standardized error system with recovery suggestions
Progress Tracking: Real-time operation status with transport information
Environment Safety: Built-in SSR protection and platform detection
Backward Compatibility: Legacy aliases maintained for gradual migration

Next Steps

Explore individual API documentation:

Camera APIs - Photo capture and permissions
File Management APIs - File picking and intent handling
Haptic APIs - Haptic feedback integration
Storage API - Universal data persistence

Available Native APIs